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Ni 


安 


npm install orm 


所 支持 的 Node.js 版 本 


支持 0.8, 0.10, 0.12, iojs-1.5 。 


0.10.x ， 0.12.x 和 iojs-1.5 版 本 的 测试 在 Travis Cl 上 运行 。 如 果 你 想 要 
的 话 ， 可 以 在 本 地 运行 测试 : 


npm test 


DBMS 支持 


e MySQL & MariaDB 

PostgreSQL 

Amazon Redshift 

SQLite 

MongoDB (beta 版 ， 到 现在 为 止 缺少 聚合 ) 


特性 


。 ERE, AS, MR, eee, RN, ah, BR, te RAW 

。 创建 模型 的 关联 ， 查 找 ， 检 查 ， 创 建 和 移 除 

定义 自 定 义 的 验证 器 〈 有 一 些 内 建 的 验证 器 ， 会 在 保存 之 前 检查 实例 的 属性 -- 

详 见 enforce 

。 模型 实例 的 缓存 和 一 致 性 (两 次 获取 表 中 的 一 行 ， 获 取 到 相同 的 对 象 ， 修 改 其 
中 一 个 就 是 修改 全 部 ) 

e 插件 : MySQLFTS, Pagination (分 页 ) , Transaction (Œ 
务 ) ，Timestamps 〈 时 间 戳 ) ，Migrations GL) 


AN 
Itza 


这 是 一 个 Node.js 对 象 关 系 映射 模块 。 


示例 : 


var orm = require("orm"); 


orm.connect("mysql://username: password@host/database", function (ei 
if (err) throw err; 


var Person = db.define("person", { 


name : String, 
surname : String, 
age : Number, // FLOAT 
male : Boolean, 
continent : [ "Europe", "America", "Asia", "Africa", "Austi 
photo : Buffer, // BLOB/BINARY 
data : Object // JSON encoded 
}, i 
methods: { 
fullName: function () { 
return this.name + ' ' + this.surname; 
} 
}, 


validations: { 
age: orm.enforce.ranges.number(18, undefined, "under -a¢ 
} 


Yr 


// add the table to the database 
db.sync(function(err) { 
if (err) throw err; 


// add a row to the person table 
Person.create({ id: 1, name: "John", surname: "Doe", age: : 
if (err) throw err; 


// query the person table by surname 

Person.find({ surname: "Doe" }, function (err, peor 
// SQL: "SELECT * FROM person WHERE surname = 
if (err) throw err; 


console.log("People found: %d", people.length) , 
console.log("First person: %s, age %d", people| 


people[O].age = 16; 
people[0].save(function (err) { 
// err.msg = "under-age"; 
3); 
}); 


PO 
}); 
leh 








Promise 


你 可 以 使 用 开启 Promise 的 包装 库 。 


Express 
如 果 你 使 用 了 Express， 你 可 能 想 使 用 这 一 简单 的 中 间 件 ， 使 集成 变 得 更 容易 。 


var express = require('express'); 
var orm = require('orm'); 
var app = express(); 


app.use(orm.express("mysql://username: password@host/database", { 
define: function (db, models, next) { 
models.person = db.define("person", { ... }); 
next(); 


})); 
app.listen(80); 
app.get("/", function (req, res) { 


// req.models is a reference to models used above in define() 
req.models.person.find(...); 


}); 
| 
你 可 以 多 次 调用 orm.express 来 获取 多 个 数据 库 的 连接 。 在 多 个 连接 之 间 定 义 的 


模型 会 在 req.models 中 连接 。 不 要 忘记 在 app.use(app.router) 之 前 使 用 
它 ， 最 好 在 你 的 公共 素材 文件 夹 之 后 。 


示例 


请 见 examples/anontxt ， 里 面 有 一 个 基于 express 的 应 用 示例 。 


连接 到 数据 库 


译 者 : 飞龙 
来 源 : Connecting to Database 


在 连接 之 前 ， 你 需要 一 个 受 支持 的 驱动 。 下 面 是 一 些 测试 过 的 驱动 及 其 版 本 ， 把 你 
所 需要 的 加 入 到 package.json 中 。 


驱动 npm 包 版 本 
mysql mysql 2.0.0-alpha9 
postgres 
redshift Pg 262m] 
sqlite sqlite3 2.1.7 
mongodb mongodb 1.3.19 


[1] 如 果 你 要 连接 到 Heroku， 请 使 用 版 本 2.5.0。 


age 过 的 版 本 ， 使 用 其 它 的 版 本 (新 的 或 者 旧 的 ) 带 来 的 风险 由 你 自己 承 
日 


例如 ， 使 用 MySQL 要 这 样 做 : 


$ npm install --save mysql@2.0.0-alpha8 


你 可 以 传递 一 个 URL 字 符 串 来 连接 数据 库 ， 其 中 scheme 为 受 支 持 的 驱动 ， 或 者 你 
可 以 传递 一 个 带 有 连接 参数 的 object 。 


var orm = require('orm'); 


orm.connect('mysql://root:password@localhost/test', function(err, « 
if (err) return console.error('Connection error: ' + err); 


// connected 
Vil were 


}); 


回调 函数 只 在 连接 建立 成 功 ( 或 失败 ) 时 调用 。 如 果 你 愿意 的 话 ， 可 以 不 传人 回调 
KA, eT connect 事件 。 





var orm = require('orm'); 
var db = orm.connect('mysql://root:password@localhost/test'); 


db.on('connect', function(err) { 
if (err) return console.error('Connection error: ' + err); 


// connected 
OA 
}); 


连接 URL 遵 循 下 面 的 语 


法 : driver://username:password@hostname/database?option1=value1&opti 
可 选 参 数 为 : 


e debug (默认 为 false ) : 将 连接 输出 到 控制 台 ; 

e pool (默认 为 false ) : 使 用 驱动 内 建 的 组 件 管理 连接 池 ( 仅 
对 mysql 和 postgres 有 效 ) ; 

e strdates (默认 为 false ) : 以 字符 串 形 式 保存 日 期 ( 仅 对 sqlite 有 
效 ) ; 

e timezone (默认 为 local ) : 在 数据 库 中 使 用 指定 的 时 区 储存 日 期 Ux 
对 mysql 和 postgres 有 效 ) ; 


debug 和 pool 也 可 以 使 用 settings 对 象 来 设置 。 


连接 到 多 个 数据 库 


ORM 模 型 受 数据 库 连 接 约束 ， 所 以 如 果 你 需要 "多 租户 ”， 即 连接 到 不 同 的 服务 器 或 
数据 库 ， 你 可 以 使 用 像 下 面 这 样 的 方法 : 


// db.js 
var connections = {}; 


function setup(db) { 


var User = db.define('user', ...); 
var Shirt = db.define('shirt', ...); 
Shirt.hasOne('user', User, ...); 


} 


module.exports = function(host, database, cb) { 
if (connections[host] && connections[host][database]) { 
return connections[host][database]; 


} 


var opts = { 
host: host, 
database: database, 
protocol: 'mysql', 
port: '3306', 
query: {pool: true} 
}; 


orm.connect(opts, function(err, db) { 
if (err) return cb(err); 


connections[host] = connections[host] || {}; 
connections[host][database] = db; 
setup(db); 
cb(null, db); 
}); 


}; 
// somewhere else, eg, middleware 
var database = require('./db'); 


database('dbserveri', 'main', function(err, db) { 
if (err) throw err; 


db.models.user.find({foo: 'bar'}, function(err, rows) { 
Tle ee 


连接 是 被 缓存 的 ， 所 以 模型 在 每 个 服务 器 + 数据 库 上 面 只 会 定义 一 次 。 由 于 我 们 使 
用 了 连接 池 ， 我 们 并 不 需要 担心 用 完 所 有 的 连接 ， 而 且 我 们 可 以 一 次 性 执行 多 个 查 
询 。 


问题 排除 


如 果 你 在 连接 MySQL 数 据 库 的 时 候 遇 到 了 如 下 错误 : 


Error: connect ECONNREFUSED 
at errnoException (net.js:670:11) 
at Object.afterConnect [as oncomplete] (net.js:661:19) 


你 可 以 党 试 添 加 socketPath BR : 


var db = orm.connect({ 


host: ‘localhost', 
database: 'database', 
user: 'user', 


password: 'pass', 
protocol: 'mysql', 
socketPath: '/var/run/mysqlid/mysqld.sock', 
port: P3306", 
query: {pool: true, debug: true} 
}); 


ie 
译 者 : 飞龙 
来 源 : Settings 


设置 用 于 储存 键 值 对 。 设 置 对 象 是 orm (默认 值 ) 上 的 实例 ， 之 后 会 为 每 
个 db 连接 和 每 个 定义 过 的 Model 建立 快照 。 所 以 orm.settings 上 的 和 更改 只 会 
作用 于 更 改 之 后 建立 的 连接 ， 而 db.settings 会 作用 于 更 改 之 后 定义 的 模型 。 
var orm = require("orm"); 
orm.settings.set("some.deep.value", 123); 
orm.connect("....", function (err, db) { 
// db.settings is a snapshot of the settings at the moment 


// of orm.connect(). changes to it don't affect orm.settings 


console.log(db.settings.get("some.deep.value")); // 123 
console.log(db.settings.get("some.deep")); // { value: 1: 


db.settings.set("other.value", { some: "object" }); 


console.log(db.settings.get("other.value")); // { some: "ok 
console.log(orm.settings.get("other.value")); // undefined 





var Settings = { 


properties : { 
primary_key 
association_key 
required 

}, 

instance Pena 
cache 
cacheSaveCheck 
autoSave 
autoFetch 
autoFetchLimit 
cascadeRemove 
returnAllErrors 

}, 

connection : { 
reconnect 
pool 
debug 


UTO, 
"{name}_{field}", 
false 


设置 
properties.primary_key 


properties.association_key 


properties.required 


instance.cache 


instance.cacheSaveCheck 


instance. autoSave 
instance.autoFetch 
instance. autoFetchLimit 


instance.cascadeRemove 


instance.returnAllErrors 


connection.reconnect 
connection.pool 


connection.debug 


描述 
在 没有 定义 id 属 性 的 模型 中 ， 定 义 主键 的 


小 


关联 键 的 属性 名 称 (例如 user_id ) 
属性 是 否 拥 有 默认 行为 


实例 是 否 应 该 被 缓存 (并 不 是 真 的 缓存 ， 
和 单 例 模式 相关 ) 


被 缓存 的 对 象 是 否 应 该 从 缓存 中 返回 (不 
要 修改 这 个 设置 ， 除 非 你 知道 自己 在 做 什 


4) 


如 果 开 启 的 话 ， 修 改 实例 的 任何 属性 时 会 
自动 保存 


是 否 需 要 自动 获取 关联 


如 果 开 启 了 自动 获取 关联 ， 这 个 设置 是 获 
取 关 联 的 深度 

删除 实例 时 是 否 要 删除 关联 

如 果 开 启 ， 实 例 保存 时 会 记录 下 所 有 的 错 
误 并 以 数组 形式 返回 ， 而 不 是 遇 到 第 一 个 
错误 就 中 止 并 返回 

连接 失效 时 是 否 党 试 重新 连接 

是 否 使 用 驱动 带 有 的 连接 池 (如 果 支 持 的 
话 ) 

向 控制 台 打 印 带 颜色 的 查询 信息 


mo . +- 
定义 模型 
译 者 : 飞龙 
来 源 : Defining Models 


在 连接 之 后 ， 你 可 以 使 用 连接 对 象 ( db ) 来 定义 你 的 模型 。 你 需要 指定 模型 的 名 
称 ， 一 个 用 于 描述 的 属性 和 一 些 (可 选 的 ) 选项 。 下 面 是 一 个 简短 的 例子 : 


var Person = db.define('person', { 


id: {type: 'serial', key: true}, // the auto-incrementing pi 
name: {type: 'text'}, 
surname: {type: 'text'}, 
age: {type: 'number'} 
tr { 

methods : { 

fullName: function() { 

return this.name + ' ' + this.surname; 





这 个 模型 叫做 person (通常 也 是 数据 库 里 面 表 的 名 称 ) ， 它 有 三 个 属性 

( name 和 surname AMA, age 为 数值 ) 。 如 果 你 自己 不 指定 任何 键 的 话 ， 
默认 的 id: { type: 'serial', key: true } 会 添加 进来 。 在 这 个 例子 中 ， 有 
个 模型 方法 叫做 fullName 。 下 面 是 这 个 模型 的 使 用 方法 的 示例 : 


Person.get(73, function(err, person) { 
if (err) throw err; 


console.log('Hi, my name is ' + person.fullName()); 


}); 


这 会 获取 id=73 的 person 对 象 ， 并 且 打 印 出 它 的 名 字 和 姓氏 。 其 它 类 型 的 可 用 
属性 请 见 这 里 。 


JS 
* @param {0bject} props Property definitions 
* @param {Object} opts Options 
人 

db.define(props, opts) 


db.define() 接收 的 第 一 个 对 象 第 二 个 参数 ) 被 称 为 属性 对 象 ， 它 定义 了 所 有 
的 属性 。 


第 二 个 对 象 指定 了 额外 的 选项 : 


选项 名 称 类 型 描述 
collection String 履 写 数据 库 中 表 的 名 称 
ere Object 人 它 会 被 设置 到 实 
hooks Object 用 户 定义 的 钩子 或 回调 
validations Object 用 户 定 义 的 验证 器 


为 了 支持 在 properties 上 设 


id A 
ee E key: true 而 不 提倡 使 用 

人 允许 你 开启 或 者 禁用 单 例 行 为 。 它 叫 
Gene Boolean 做 cache ， 但 是 和 缓存 毫 无 关系 。 
autoSave Boolean 不 推荐 。 在 属性 修改 时 自动 保存 模型 。 
autoFetch Boolean 是 否 自动 获取 关联 
autoFetchLimit Number 自动 获取 关联 的 深度 


cascadeRemove Boolean 删除 实例 时 是 否 要 删除 关联 


模型 属性 


译 者 : 飞龙 

来 源 : Model Properties 
模型 和 一 些 关联 有 具有 一 个 或 多 个 属性 ， 每 个 属性 有 类 型 以 及 一 些 可 选 设置 ， 你 可 以 
自行 选择 它们 (或 使 用 默认 设置 ) 。 


N Z 1 


受 支持 的 类 型 是 : 
e text : 文本 字符 串 ; 
e number : 浮 点 数 。 你 可 以 指定 size HA 2141/8 ; 
e integer : 整数 。 你 可 以 指定 size 为 2|4|8; 
e boolean : true 或 false 的 值 ; 
e date : 日 期 对 象 。 你 可 以 指定 time 为 true ; 
e enum : 一 个 各 选 列 表 中 的 值 ; 
e object : JSON 对 象 ; 
e point : N 维 的 点 (不 被 广泛 支持 ) 
e binary :二进制 数据 ; 
e serial : 自 增长 的 整数 ， 用 于 主键 。 


每 个 类 型 都 有 额外 的 选项 。 这 个 模型 定义 使 用 了 它们 中 的 绝 大 多 数 : 
var Person = db.define("person", { 
name { type: "text", size: 50 }, 
surname : { type: "text", defaultValue: "Doe" }, 
male : { type: "boolean" }, 
vat : { type: "integer", unique: true }, 
country : { type: "enum", values: [ "USA", "Canada", "Rest of 1 
birth { type: "date", time: false } 
}); 


人 Eee 
所 有 类 型 都 支持 required (布尔 值 ) ， unique (布尔 值 ) 
和 defaultValue (XF) 。 文 本 类 型 也 支持 最 大 尺寸 (数值 ) 和 big (布尔 


值 ， 用 于 非常 长 的 字符 串 ) 。 数 值 类 型 是 浮 点 数 ， 支 持 size (数值 ， 字 节 大 小 ) 
和 unsigned (布尔 值 ) 。 日 期 类 型 支持 time (布尔 值 ) 。 


要 注意 8 字 节 的 数值 有 其 局 限 性 。 
如 果 你 打算 用 默认 选项 ， 你 可 以 使 用 原生 类 型 来 指定 属性 类 型 : 





var Person = db.define("person", { 


name : String, 

male : Boolean, 

vat : Number, // FLOAT 

birth : Date, 

country : [ "USA", "Canada", "Rest of the World" ], 
meta : Object, // JSON 

photo : Buffer // binary 


}); 


将 ORM 字 段 映 射 到 不 同名 称 的 效 据 库 列 中 


var Person = db.define("person", { 
name : { type: ‘text’, mapsTo: ‘fullname’ } 


}); 


ORM 属 性 name 映射 person 表 的 fullname 列 。 


自 定 义 类 型 
你 可 以 向 ORM 添 加 你 自己 的 类 型 ， 像 这 样 : 


db.defineType('numberArray', { 
datastoreType: function(prop) { 
return 'TEXT' 
ty 
// This is optional 
valueToProperty: function(value, prop) { 
if (Array.isArray(value)) { 
return value; 
} else { 
return value.split(',').map(function (v) { 
return Number(v); 
}); 
} 
ty 


// This is also optional 

propertyToValue: function(value, prop) { 
return value.join(',') 

} 


}); 
var LottoTicket = db.define('lotto_ticket', { 


numbers: { type: 'numberArray' } 


}); 


一 些 可 用 的 高 级 自 定义 类 型 ， 能 够 让 你 像 PostGIS 那样 使 用 模型 。 请 见 这 个 spec 


o 


模型 验证 器 


译 者 : 飞龙 

来 源 : Model Validations 
Enforce 模 块 用 于 验证 数据 。 对 于 使 用 以 前 的 验证 器 的 用 户 ， 还 可 以 继续 使 用 ， 它 
们 中 的 一 部 分 整合 到 了 enforce， 剩 余部 分 还 没有 。 推荐 你 开始 使 


FA orm.enforce 来 取代 orm.validators 。 可 用 的 验证 器 的 列表 请 见 node- 
enforce。 


unique 验证 器 也 构建 于 ORM 中 ， 可 以 这 样 来 访问 : 
name: orm.enforce.unique("name already taken!") 


name: orm.enforce.unique({ scope: ['age'] }, "Sorry, name already 1 
name: orm.enforce.unique({ ignoreCase: true }) // 'John' is same a: 


a o 


你 可 以 为 模型 的 每 个 属性 定义 验证 器 。 对 于 每 个 属性 ， 你 可 以 定义 一 个 或 多 个 验证 
器 。 你 也 可 以 使 用 预定 义 的 验证 器 ， 或 者 自己 新 建 。 





var Person = db.define("person", { 
name : String, 
age : Number 
} i 
validations : { 
name : orm.enforce.ranges.length(1, undefined, "missing"), 
age : [ orm.enforce.ranges.number(0, 10), orm.enforce.lisi 





上 面 的 代码 限定 了 name 的 长 度 必须 在 1 和 undefined 之 间 (undfined 表 示 任 意 

值 ) ， 以 及 age 必须 在 0 和 10 (HRA) 之 间 ， 而 且 是 列 出 的 值 之 一 。 这 个 例子 或 
许 没 有 意义 ， 但 是 足够 解释 了 。 

保存 一 个 对 象 的 时 候 ， 如 果 由 任何 一 个 验证 器 验证 失败 ， 你 都 会 得 到 一 个 带 有 属性 
名 称 和 验证 错误 描述 的 error 对 象 。 这 个 描述 可 以 帮助 你 弄 清 楚 发 生 了 什么 。 


var John = new Person({ 


name : 

age : 20 
+); 
John.save(function (err) { 

// err.field = "name" , err.value = "" , err.msg = "missing" 
p); 


在 第 一 个 验证 器 验证 失败 之 后 ， 验 证 就 停止 了 。 如 果 你 想 要 验证 每 个 属性 并 且 返 回 
所 有 验证 错误 ， 你 可 以 在 全 局 或 局 部 设置 中 更 改 这 一 行为 : 


var orm = require("orm"); 


orm.settings.set("instance.returnAllErrors", true); // global or.. 


orm.connect("....", function (err, db) { 
db.settings.set("instance.returnAllErrors", true); // .. local 
OA 
var John = new Person({ 
name : "", 
age : 15 


D 


John.save(function (err) { 
assert(Array.isArray(err)); 
// err[0].property = "name" , err[0].value 
// err[1].property 
// err[2].property 


uw, err[0].ms 
15 , err[1].m: 
15 , err[2].ms 


"age" , err[1].value 
"age" , err[2].value 





模型 钩子 


译 者 : 飞龙 
来 源 : Model Hooks 
如 果 你 想 要 监听 发 生 在 模型 实例 上 的 事件 ， 你 可 以 附带 一 个 函数 ， 它 会 在 发 生 时 调 


o 


现在 支持 下 面 这 些 事件 : 


e afterLoad : (ABM) 加 载 和 准备 所 用 实例 之 

e afterAutoFetch : (无 参数 ) 自动 获取 关联 aS 之 后 ， 无 论 有 
没有 关联 都 会 触发 ; 

e beforeSave : (ABM) 尝试 保存 之 前 ; 

e afterSave : (boolsuccess) 保存 之 后 ; 

e beforeCreate : (ABM) 尝试 保存 新 的 实例 之 前 (优先 

于 beforeSave ) 

afterCreate : (boolsuccess) 保存 新 的 实例 之 后 

beforeRemove : (无 参数 ) 尝试 删除 实例 之 前 ; 

afterRemove : (bool success) 删除 实例 之 后 

beforeValidation : (无 参数 ) 在 所 有 验证 之 前 ， 优 先 

于 beforeCreate 和 beforeSave 。 


PAAF RBA, this 为 对 应 的 实例 ， 所 以 你 可 以 访问 到 与 之 相关 的 任何 东 
西 。 


对 于 所 有 before* 钧 子 ， 你 可 以 添加 一 个 额外 的 参数 到 钩子 函数 中 。 这 个 函数 用 
告诉 钧 子 应 该 继续 执行 下 去 还 是 中 断 。 你 或 许 已 经 从 Express 的 工作 流 中 熟悉 了 
一 点 。 下 面 是 一 个 示例 : 


var Person = db.define("person", { 


name : String, 
surname : String 
} í 
hooks: { 
beforeCreate: function (next) { 
if (this.surname == "Doe") { 


return next(new Error("No Does allowed")); 


return next(); 


}); 


这 个 工作 流 允 许 你 在 调用 next 之 前 执行 异步 的 操作 。 如 果 你 不 打算 使 
用 next 就 不 要 把 它 定义 为 参数 ， 否 则 会 阻塞 工作 流 。 


Fe JL i) 


一 个 常见 问题 涉及 到 在 钩子 内 部 的 挫 套 回调 中 访问 this 。 这 个 问题 的 原因 

是 ， this 对 象 仅 仅 在 顶级 钩子 函数 的 作用 域内 是 有 效 的 ， 而 在 回调 中 会 有 各 种 不 
同 的 值 。 要 解决 这 一 问题 ， 可 以 创建 一 个 对 象 保 存 this 的 引用 ， 并 且 在 回调 中 用 
它 来 访问 模型 的 属性 。 


示例 
var Person = db.define("person", { 
name : String, 
surname : String 
} { 
hooks: { 


beforeCreate: function (next) { 
var _this = this; 
checkName(this, function(err, result)) { 
if(err) return next(err); 
_this.name = result.name; 
_this.surname = result.surname; 
next(); 


3); 


orm2 中 文 文档 


mo 、 
定义 关联 

译 者 : 飞龙 

来 源 : Defining Associations 
关联 是 一 个 或 多 个 模型 之 间 的 关系 。 
关联 的 类 型 : 


e hasOne (多 对 一 ) 
e hasMany (多 对 多 ) 
e extendsTo (一 对 一 ) 


定义 关联 


25 


hasOne (多 对 一 关系 ) 


译 者 : 飞龙 
来 源 : hasOne 
EN T 种 多 对 一 的 关系 ， 忆 意思 是 你 定义 的 模型 可 以 有 多 个 实例 指 向 一 


它 的 实例 所属 相同 模型 或 不 同 模型 】。 
用 法 


Animal.hasOne(association_name [, association_model [, options ] ] 





e association_name 是 两 个 模型 之 间 的 关系 名 称 ' 

e association model 是 要 关联 的 另 一 个 模型 《如果 没 有 定义 ， 假 设 为 同一 个 
模型 ， 大 多 数 情况 下 这 可 能 不 是 你 想 要 的 ) ; 

e options 是 一 个 对 象 ， 拥 有 一 些 和 关联 有 关 的 ， 你 可 以 调整 的 属性 ， 比 如 自 
动 获 取 ， 再 比如 表 (SQL 中 ) 或 者 集合 (MongoDB 中 ) 的 名 称 。 


示例 


Animal.hasOne("owner", Person); 


在 背后 ， 这 条 语句 意思 是 Animal 集合 拥有 一 个 属性 owner_id (这 个 名 称 可 以 
通过 选项 来 修改 ， {field: 'ownerid'} ) ， 它 会 指向 Person 集合 的 某 个 人 。 
如 果 关 联 并 不 是 必须 的 ， 则 可 以 为 空 。 


这 个 关联 也 会 创建 一 些 额 外 的 便利 方法 (叫做 关联 访问 器 ) 来 帮助 你 管理 它 。 访 问 
器 的 名 称 也 可 以 修改 (同上 ， 在 选项 里 面 ) ， 默 认 情 况 下 ， 它 们 会 拥有 和 关联 名 称 
相似 的 名 称 。 例 如 ， 下 面 的 代码 展示 了 可 以 做 类 似 这 样 的 事情 : 


// assuming John is a Person.. 
Animal.find({ name: "Deco" }).first(function (err, Deco) { 
Deco.setOwner(John, function (err) { 
// John is now the owner of Deco 
+); 
+); 


其 它 的 访问 器 : 


e getOwner(callback) -获取 关联 的 所 有 者 
e hasOwner(callback) - (在 回调 中 ) 返回 这 个 动物 是 否 拥 有 所 有 者 
e removeOwner(callback) - 移 除 和 所 有 者 的 关联 关系 GREENE) 


关联 反 转 


有 时 你 希望 通过 对 面 的 模型 来 访问 关联 。 在 上 面 的 例子 中 ， 是 通过 Person 。 你 可 
以 向 关联 传递 一 个 选项 来 实现 它 。 


Animal.hasOne('owner', Person, { reverse: "pets" }); 


之 后 ， 每 个 person 实例 都 有 有 两 个 便利 方法 : 


e getPets(callback) -获取 所 有 和 这 个 人 有 关联 的 动物 
e setPets(cat, dog, callback) - 移 除 所 有 和 这 个 人 有 关联 的 动物 ， 并 且 添 
加 猫 和 狗 


hasMany (多 对 多 关系 ) 


译 者 : 飞龙 
来 源 : hasMany 


hasMany 


是 多 对 多 的 关系 (包括 连接 表 ) 。 
例 


如 : Patient.hasMany('doctors', Doctor, { why: String }, { reverse: ' 


o 


病人 可 以 拥有 许多 不 同 的 医生 。 每 个 医生 可 以 拥有 许多 不 同 的 病人 。 
当 你 调用 Patient.sync() 时 ， 会 创建 一 个 连接 表 patient_doctors o 


列 名 称 类 型 
patient_id Integer 
doctor_id Integer 
why varchar(255) 


下 列 函 数 是 可 用 的 : 


// 获取 所 有 关联 医生 的 列表 
patient.getDoctors(function(err, doctors) { 
OA 


}); 


// 向 连接 表 中 增加 记录 
patient.addDoctors([phil, bob], function(err) { 
OA 


}); 


// 移 除 连接 表 中 的 现 有 记录 ， 并 增加 新 的 
patient.setDoctors([phil, nephewOfBob], function(err) { 
Veh eli 


}); 


// 检查 是 否 某 个 病人 关联 了 指定 的 医生 

patient.hasDoctors([bob], function(err, patientHasBobAsADoctor) { 
// because that is a totally legit and descriptive variable name 
if (patientHasBobAsADoctor) { 


// 从 连接 表 中 移 除 指定 记录 
patient.removeDoctors([bob], function(err) { 
a ere 


}); 


// 并 且 所 有 医生 都 有 自己 的 方法 来 获取 病人 
bob.getPatients(function(err, patients) { 
if (patients.indexOf(you) !== -1) { 
// woot! 
} else 
OA 


} 
}); 
// 以 及 其 他 
:| 
要 把 医生 关联 到 病人 : 


patient.addDoctor(surgeon, {why: 'remove appendix'}, function(err) 


TL TOR 
surgeon.addPatient(patient, {why: ‘remove appendix'}, function(err. 


Ii aar 
}); 








这 样 会 添加 {patient id: 4, doctor_id: 6, why: "remove appendix"} 到 连 


接 表 中 。 


API 


Model .hasMany( 
name, // String. 关联 名 称 


otherModel, // Model. 要 关联 的 模型 
extraProps, // Object. 在 连接 表 上 出 现 的 额外 属性 
opts // Object. 关联 的 选项 


); 


选项 名 称 
autoFetch 
autoFetchLimit 
key 


merge Table 
mergeld 


mergeAssocld 


reverse 


getAccessor 


setAccessor 


hasAccessor 


delAccessor 


addAccessor 


类 型 
Boolean 
Number 
Boolean 


String 
String 
String 


String 


String 


String 


String 


String 


String 


描述 


默认 为 false 。 如 果 为 true ， 关 联 将 会 自动 
被 获取 。 


默认 为 1 。 自 动 获取 的 深度 。 


默认 为 false (由 于 历史 原因 ) 。 如 果 
为 true ， 表 中 外 键 的 列 会 形成 一 个 组 合 键 。 


连接 表 的 自 定义 名 称 

代表 当前 模型 那 一 列 的 自 定 义 名 称 

代表 另 一 个 模型 那 一 列 的 自 定义 名 称 

默认 为 false 。 如 果 为 true ， 关 联 可 以 通过 
另 一 个 模型 使 用 指定 方法 获取 到 。 

'get' + Name 。 人 允许 重 命 名 关联 访问 


默认 为 'set' + Name 。 人 允许 重 命 名 关联 访问 
Zins 
默认 为 'has' + Name 。 人 允许 重 命 名 关联 访问 
Zao 
默认 为 'del' + Name 。 人 允许 重 命 名 关联 访问 
Aine 
默认 为 'add' + Name 。 人 允许 重 命 名 关联 访问 


o 


extendsTo (一 对 一 关系 ) 


译 者 : 飞龙 
来 源 : extendsTo 


你 可 能 想 把 可 选 的 属性 分 割 到 另 一 个 表 中 。 每 个 扩展 都 会 是 一 个 新 的 表 ， 其 中 每 一 
行 的 唯一 标识 符 是 主 模型 实例 的 id。 


例如 : 


var Person = db.define("person", { 
name : String 


var PersonAddress = Person.extendsTo("address", { 
street : String, 
number : Number 


+); 


这 样 会 创建 person X, #8 id 和 name 列 。 扩 展 行为 会 创 

建 person_address X, # 

有 person_id , street 和 number J, Person 模型 中 可 用 的 方法 类 似 
于 hasone 关联 。 这 个 例子 中 ， 你 可 以 调 

用 .getAddress(cb) , .setAddress(Address, cb) 以 及 其 他 。 


注意 : 你 并 不 需要 保存 Person .extendsTo 的 返回 值 ， 它 返回 了 一 个 扩展 模型 。 
你 可 以 使 用 它 来 直接 查询 扩展 表 (甚至 查找 相关 的 模型 ) ， 但 是 这 完全 取决 于 你 。 
如 果 你 只 希望 通过 原 模 型 来 访问 它 的 话 ， 可 以 丢弃 返回 值 。 


同步 和 删除 模型 


译 者 : 飞龙 
来 源 : Syncing and dropping models 


同步 是 一 项 功能 方法 ， 可 以 在 数据 库 里 为 你 的 模型 和 关联 创建 所 需 的 表 来 工作 。 现 
存 的 表 并 不 会 被 替换 ， 它 们 只 会 在 不 存在 的 时 候 被 创建 。 


同步 有 两 种 方式 : 


1. 调用 Model.sync(cb) 会 仅仅 同步 指定 模型 
2. 调用 db.sync(cb) 会 同步 所 有 模型 


删除 是 一 个 类 似 的 方法 ， 但 是 它 会 删 掉 你 模型 涉及 的 所 有 表 ， 即 使 不 是 ORM 创 建 
的 。 删 除 也 有 两 种 方式 。 


var orm = require("orm"); 


orm.connect("....", function (err, db) { 
var Person = db.define("person", { 
name : String 
H); 
var Pet = db.define("pet", { 
name : String 


}); 


db.drop(function () { 
// 从 指定 模型 中 删除 所 有 表 (Person 和 Pet) 


Person.sync(function () { 
// 为 Person 模 型 创建 表 
}); 
}); 
}); 


查找 记录 


译 者 : 飞龙 
来 源 : Finding items 


find 
查找 匹配 标准 的 记录 ， 可 以 链 式 查询 ( 见 下 文 ) 


Person.find({status: 'active'}, function(err, results) { 
人 


P) 


你 也 可 以 限制 结果 的 个 数 ， 这 条 语句 限制 结果 为 10 个 : 


Person.find({status:'active'}, 10, function(err, results) { 
AR 


}); 


Person.all 是 Person.find 的 别名 。 
get 
通过 主键 来 查找 记录 。 


Person.get(1, function(err, person) { 
YP Gite 


}); 


one 
只 查找 一 个 记录 ， 和 find 的 语法 相似 。 


Person.one({status:'active'}, function(err, person) { 


获取 所 匹配 记录 的 数量 。 


Person.count({status:'active'}, function(err, activePeopleCount) { 


ki — g 





exists 
测试 匹配 你 的 条 件 的 记录 是 否 存 在 。 


Person.exists({id:1, status:'active'}, function(err, personIsActive 
lo ane 
+); 


a) 


at 8 AU HEE 


我 们 接受 两 个 对 象 来 执行 过 滤 〈 第 一 个 ) 和 聚合 (第 二 个 ) 。 聚 合 对 象 接 
受 limit , order 和 groupBy 。 





https://github.com/dresende/node- 
orm2/blob/v2.1.20/lib/AggregateFunctions.js#L36 


Person. find({status: 'active'}, {limit:10}, function(err, res) { 


}); 


find / count / one 等 方法 的 条 件 查 询 


所 有 以 逗号 分 隔 的 键 值 对 在 查询 中 都 会 以 AND 连接 。 你 可 以 把 逻辑 运算 符 放 在 一 
系列 条 件 的 前 面 。 


Person.find({or:[{col1i: 1}, {col2: 2}]}, function(err, res) { 
// res 为 coli == 1 或 者 col2 == 2 的 Person 
}); 


使 用 IN 来 查找 


sql-query 《取决 于 SQL 引擎 ) 会 自动 将 数组 视 为 基于 IN 的 查询 。 


https://github.com/dresende/node-sql-query/blob/v0O.1.23/lib/Where.js#L1 72 


Person.find({id: [1, 2]}, function(err, persons) { 
// 查找 id 是 1 或 者 2 的 Person (例如 WHERE id IN (1, 2) ) 
+); 


创建 和 更 新 记录 


译 者 : 飞龙 
来 源 : Creating and Updating Items 


创建 


var newRecord = {}; 
newRecord.id = 1; 


newRecord.name = "John" 
Person.create(newRecord, function(err, results) { 
J); 


保存 


Person.find({ surname: "Doe" }, function (err, people) { 
// SQL: "SELECT * FROM person WHERE surname = 'Doe'" 


console.log("People found: %d", people.length); 
console.log("First person: %s, age %d", people[0].fullName(), Į 


people[O0].age = 16; 
people[0].save(function (err) { 
// err.msg = "under-age"; 


P); 





aM 
D 


译 者 : 飞龙 

来 源 : Aggregation 
如 果 你 需要 从 一 个 模型 中 获取 一 些 聚 合 值 ， 你 可 以 使 用 Model.aggregate() o F 
面 通 过 一 个 例子 来 展示 : 


Person.aggregate({ surname: "Doe" }).min("age").max("age").get( func 
console.log("The youngest Doe guy has %d years, while the olde: 


}); 
[E| TE) 


可 以 传递 一 个 含有 属性 的 array 来 选择 仅仅 保留 一 小 部 分 属性 。 方 法 也 会 接收 一 
个 Object 来 定义 条 件 。 


下 面 是 一 个 展示 如 何 使 用 .groupBy() 的 例子 : 





// 和 "select avg(weight), age from person where country='someCount 

Person.aggregate(["age"], { country: "someCountry" }).avg("weight". 
// stats 是 一 个 数组 ， 每 个 记录 都 有 'age' 和 'avg_weight' 属性 

+); 


a -= 


基本 的 .aggregate() 方法 


e limit() : 你 可 以 传递 一 个 数值 作为 个 数 ， 或 者 两 个 数值 分 别 作 为 偏 移 和 个 
数 





e order() :和 Model.find().order() 相同 


额外 的 .aggregate() 方法 


min 
max 
avg 
sum 
count 〈 它 有 一 个 快捷 方式 - Model.count ) 


有 更 多 的 聚合 汞 数 是 依赖 于 驱动 的 《上 比如 数学 函数 ) 。 


